This invention relates to computer-based documentation and instruction.
A typical computer system as shown in FIG. 1 includes a computer 11 having a central processing unit 12, an input/output unit 13 and a memory 14 containing various programs used by the computer 11 such as an operating system 15 and one or more application programs 16. An end-user of the computer system communicates with the computer 11 by means of various input devices (keyboard 17, mouse 18) which transfer information to the computer 11 via input/output unit 13. The computer 11 replies to this input data, among other ways, by providing responsive output to the end-user, for example, by displaying appropriate text and images on the screen of a display monitor 19.
The operating system 15 may include a graphical user interface (xe2x80x9cGUIxe2x80x9d) by which the operating system and any applications it may be running (e.g., a word-processing program) can communicate with a user of the computer system. A commonly used GUI implementation employs a desktop metaphor in which the screen of the monitor is regarded as a virtual desktop. The desktop is an essentially two-dimensional working template area supporting various graphical objects, including one or more display regions. As shown in FIG. 2, information generated by application programs or the operating system can be displayed on the desktop 21 within display regions 23 (e.g., windows, dialog boxes, pop-up menus, pull-down menus, drop-down lists, icons). The user can interact with the operating system, and any applications it may be running, by manipulating the cursor 24 appropriately within the display regions and by entering information with the keyboard or other input device.
To use an application program effectively, a user must know not only how to interact with the application itself, but depending on the nature of the application, the user also must possess a body of substantive knowledge relating to the subject matter to which the application pertains. For example, if the application is a software development environment, the user must be familiar with computer programming concepts and programming languages to use the application effectively.
Most computer applications provide an online help/documentation facility which aids in the use of the application. A typical online help system such as shown in FIG. 3A is accessed through a GUI in which screens of textual and graphical information are displayed to the user in a help window 30. The user can then read the screens of help text to get a better understanding of the application and its various features.
The user invokes the help system with a key sequence (e.g., pressing the Fl key on the keyboard) or by clicking the mouse on an appropriate graphical icon or menu item. In response, the help system may display a table of contents 31 listing the available help topics and subtopics which can be accessed and viewed by the user as desired. The user can browse through the table of contents 31 and click a help topic of interest to cause its corresponding body of information to be displayed in a help window. In the help window 30 shown in FIG. 3A, the user has clicked the xe2x80x9cProgramming with Microsoft Wordxe2x80x9d topic 31 to cause the corresponding help screen 32 to be displayed in window 30 as shown in FIG. 3B.
The xe2x80x9cProgramming with Microsoft Wordxe2x80x9d topic 31 shown in FIG. 3B includes several subtopics 33, each represented by a separate xe2x80x9clink.xe2x80x9d When the user clicks the mouse on one of these linksxe2x80x94for example, the xe2x80x9cError Messagesxe2x80x9d link 34xe2x80x94the text for the corresponding help topic is displayed automatically in the help window 30, as shown in FIG. 3C. In this example, the xe2x80x9cError Messagesxe2x80x9d topic 35 includes several links to further subtopics relating to specific types of error messages. As shown in FIG. 3D, when the user clicks one of these links, for example, the xe2x80x9cOut of memory (stack space)xe2x80x9d link 25, a new help window 36 is spawned to display the corresponding help information (xe2x80x9cFreeing up memoryxe2x80x9d) for the selected topic. The help information displayed in window 36 includes yet another link 37 for another subtopic, xe2x80x9cactive window,xe2x80x9d which when clicked by the user causes corresponding help text to appear in a pop-up dialog box 38. Virtually any level of such nested help displays is possible. The quantity and types of display regions (windows, dialog boxes, etc.) used to display help information is largely a matter of design choice based on the preferences of the help system developer.
A help system may provide xe2x80x9ccontext-sensitivexe2x80x9d help information, meaning that the help system automatically displays help information specifically relevant to the application""s current task, rather than simply displaying all available help topics and forcing the user to identify and call-up the appropriate help topic manually. A context-sensitive help system decides which help information to display based on factors such as the current state of the application (e.g., the particular function being invoked by the user) and the current cursor position.
The information provided by most online help systems relates to the mechanics of using features of an application. In FIG. 4, for example, the text 42 corresponding to the chosen help topic 41, xe2x80x9cCancel printing,xe2x80x9d describes how to control the print feature provided by the application 40 (Microsoft Word).
A help system also may provide substantive information on how to make use of the application to achieve a desired goal. In Fig. 5A, for example, the online help system provides two types of substantive information: reference material 51 for the WordBasic programming language and practical explanations 52 of how to use WordBasic to write useful programs. The reference material 51 includes textual annotations describing the syntax and meaning of various WordBasic statements, such as the AddAddln statement, the help text for which is shown in FIG. 5B. The practical explanations 52 can include static examples of program code which the user can study to gain a better understanding of the WordBasic programming language. FIG. 5C shows an example of program code that makes use of the GetCurValues WordBasic statement.
Online help systems typically are xe2x80x9cbuiltxe2x80x9d (i.e., processed into a form that facilitates run-time operation) by compiling several different help source files containing help information that has been composed by technical writers. In general, these help source files are maintained as a separate body of information apart from the application to which the help system corresponds. Consequently, when the application developers change or update the functionality of the application, the technical writers must make corresponding changes to the help source files to ensure that the online help system accurately describes the operation of the application.
In one aspect, user instruction on a computer system involves performing an interactive example or instructional demonstration and providing, in synchronization with the interactive example, explanatory information corresponding to the example. The explanatory information presented explains what most recently occurred in the interactive example and is updated automatically to correspond with the current state of the interactive example. The explanatory information may be presented concurrently or simultaneously with output from the interactive example. A user of the computer system is enabled to control the performance of the interactive example or the presentation of explanatory information.
Presentation of the explanatory information can include displaying multiple windows on a screen of the computer system, the explanatory information being displayed in one window and the output from the interactive example being displayed in another window. In response to a change in state of the interactive example, the explanatory information provided may be altered accordingly.
A user of the computer system also may be provided with access to online reference materials relating to the interactive examples, the explanatory information, or both. The online reference materials may be accessed through links in the explanatory information. When a user selects a particular link, for example, by clicking the link with a mouse cursor, corresponding reference information is presented to the user. The links in the explanatory information can be arranged in a logical hierarchy, each successive level in the hierarchy providing an increased degree of detail.
A user of the computer system also may be provided with access to source code associated with an interactive example. A fragment of source code associated with an interactive example may be displayed in an annotation associated with the example. The annotation also may include a prose description of the interactive example""s operation. Access to the source code can be provided by an editing utility, which can be launched when a user of the computer system selects a visually indicated jump (e.g., a short-cut arrow) within the annotation. The user then can view, copy or modify the source code fragment in the context of the source code for the entire interactive example. The user can experiment with an interactive example by iteratively modifying the example""s source code and then executing the modified example to see what happens.
An application for implementing concepts illustrated by the interactive examples may be provided to the user. The interactive examples provided by the computer-based instructional system can represent a subset of the functionality provided by the application. For example, the interactive examples may correspond to computer programming concepts. In that case, a software development environment may be provided to allow the user to implement the programming concepts illustrated by the interactive examples.
The interactive examples and the corresponding annotations describing the interactive examples can be built from a unified body of source code. Markup symbols, demarcating a portion of the source code to be used in building an interactive example and another portion of the source code to be used in building an annotation describing the interactive example, can be included in the unified body of source code. The portion of the source code to be used in building an interactive example can overlap the portion of the source code to be used in building the annotation describing the interactive example.
In another aspect, computer software can be developed by maintaining a body of source code for a computer-based application (e.g., an instructional example) and building the computer-based application based on the body of source code. Moreover, an annotation corresponding to the computer-based application can be built based on information extracted from the body of source code. The body of source code that is maintained can include both program instructions and explanatory information, which programmers (or a processing script) can distinguish from each other based symbols (e.g., markup symbols) appearing throughout the body of source code. The symbols can identify program instructions that are to be used for building interactive examples or source code fragments that are to be displayed to an end-user. Alternatively, or in addition, the symbols can define a manner in which the explanatory information is to be presented to an end-user.
An annotation can be built by parsing the body of source code to identify portions of the source code that correspond to the annotation. Parsing can be accomplished by processing the body of source code with a script that recognizes predetermined markup symbols appearing in the body of source code. Building of an annotation also may involve generating documentation source files based on a result of the parsing. The documentation source files then can be compiled into a format recognized by an online help utility. Parsing of the source code also can be used to generate example source code files, which can be compiled into interactive examples that can be executed by an end-user.
Development of the software also may include generating a jump that allows an end-user to access the body of source code at a location corresponding to a source code fragment displayed adjacent to the jump. Moreover, software development can include assembling a list of predetermined tokens (e.g., keywords or class names) appearing in the body of source code and generating a link to an online reference for each token in the assembled list.
Advantages may include one or more of the following. An instructional help system based on the documentation by example concept provides a learning environment, or laboratory, where users are provided with representative examples of proven techniques for successfully operating the application to accomplish a desired goal (e.g., programming a new application). By executing, inspecting, modifying, and copying from the examples provided, users are able to learn complex and sophisticated subject matters at an accelerated rate.
The documentation by example system described here provides enhanced training and instruction capabilities. Users can selectively execute any of several interactive examples and learn by observing their operation. In addition, a user""s observations are reinforced by annotations which are displayed to the user as the example is executing. The annotations are coordinated automatically with execution of the examples such that the annotation text displayed at any given time is synchronized with the state of the example. As a result, the user can discern what just happened in the example by reading the annotation appearing on the screen. Moreover, users can learn more about the example at a desired level of detail by following links in the annotation to relevant background information.
The manner in which the documentation by example system is built and maintained guarantees that the interactive examples and their respective annotations are kept in synchronization. Because the source code for the interactive examples and the corresponding descriptive information are extracted directly from the same body of source code, the annotations always will reflect the current functionality of the interactive examples. Moreover, by including the examples"" source code and their corresponding annotations within the same body of source code, maintenance of the documentation by example system is simplified dramatically. Because the components of the documentation by example system are integrated into, and updated along with, the interactive examples"" source code, software developers need not separately update and build the documentation by example system each time the examples are changed. As a result, the interactive examples can be updated freely and frequently without incurring the administrative headaches of manually ensuring that the documentation system includes the most recent or correct versions of examples and their annotations.